/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Marks a constructor, field, setter method, or config method as to be autowired by Spring's
 * dependency injection facilities. This is an alternative to the JSR-330 {@link
 * javax.inject.Inject} annotation, adding required-vs-optional semantics.
 *
 * <h3>Autowired Constructors</h3>
 * <p>Only one constructor of any given bean class may declare this annotation with the
 * {@link #required} attribute set to {@code true}, indicating <i>the</i> constructor to autowire
 * when used as a Spring bean. Furthermore, if the {@code required} attribute is set to {@code
 * true}, only a single constructor may be annotated with {@code @Autowired}. If multiple
 * <i>non-required</i> constructors declare the annotation, they will be considered as candidates
 * for autowiring. The constructor with the greatest number of dependencies that can be satisfied by
 * matching beans in the Spring container will be chosen. If none of the candidates can be
 * satisfied, then a primary/default constructor (if present) will be used. If a class only declares
 * a single constructor to begin with, it will always be used, even if not annotated. An annotated
 * constructor does not have to be public.
 *
 * <h3>Autowired Fields</h3>
 * <p>Fields are injected right after construction of a bean, before any config methods
 * are invoked. Such a config field does not have to be public.
 *
 * <h3>Autowired Methods</h3>
 * <p>Config methods may have an arbitrary name and any number of arguments; each of
 * those arguments will be autowired with a matching bean in the Spring container. Bean property
 * setter methods are effectively just a special case of such a general config method. Such config
 * methods do not have to be public.
 *
 * <h3>Autowired Parameters</h3>
 * <p>Although {@code @Autowired} can technically be declared on individual method
 * or constructor parameters since Spring Framework 5.0, most parts of the framework ignore such
 * declarations. The only part of the core Spring Framework that actively supports autowired
 * parameters is the JUnit Jupiter support in the {@code spring-test} module (see the
 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html#testcontext-junit-jupiter-di">TestContext
 * framework</a>
 * reference documentation for details).
 *
 * <h3>Multiple Arguments and 'required' Semantics</h3>
 * <p>In the case of a multi-arg constructor or method, the {@link #required} attribute
 * is applicable to all arguments. Individual parameters may be declared as Java-8 style {@link
 * java.util.Optional} or, as of Spring Framework 5.0, also as {@code @Nullable} or a not-null
 * parameter type in Kotlin, overriding the base 'required' semantics.
 *
 * <h3>Autowiring Arrays, Collections, and Maps</h3>
 * <p>In case of an array, {@link java.util.Collection}, or {@link java.util.Map}
 * dependency type, the container autowires all beans matching the declared value type. For such
 * purposes, the map keys must be declared as type {@code String} which will be resolved to the
 * corresponding bean names. Such a container-provided collection will be ordered, taking into
 * account {@link org.springframework.core.Ordered Ordered} and {@link
 * org.springframework.core.annotation.Order @Order} values of the target components, otherwise
 * following their registration order in the container. Alternatively, a single matching target bean
 * may also be a generally typed {@code Collection} or {@code Map} itself, getting injected as
 * such.
 *
 * <h3>Not supported in {@code BeanPostProcessor} or {@code BeanFactoryPostProcessor}</h3>
 * <p>Note that actual injection is performed through a
 * {@link org.springframework.beans.factory.config.BeanPostProcessor BeanPostProcessor} which in
 * turn means that you <em>cannot</em> use {@code @Autowired} to inject references into {@link
 * org.springframework.beans.factory.config.BeanPostProcessor BeanPostProcessor} or {@link
 * org.springframework.beans.factory.config.BeanFactoryPostProcessor BeanFactoryPostProcessor}
 * types. Please consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor} class
 * (which, by default, checks for the presence of this annotation).
 * <p>
 * 自动装配注解
 *
 * @author Juergen Hoeller
 * @author Mark Fisher
 * @author Sam Brannen
 * @see AutowiredAnnotationBeanPostProcessor
 * @see Qualifier
 * @see Value
 * @since 2.5
 */
@Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD, ElementType.ANNOTATION_TYPE })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Autowired {

	/**
	 * Declares whether the annotated dependency is required.
	 * <p>Defaults to {@code true}.
	 */
	boolean required() default true;

}
